HAL I3C Functions

Acquire/release the bus

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group10

A set of functions that acquire or release the bus based on the HAL OS abstraction layer (stm32_hal_os.c/.h osal):

• HAL_I3C_AcquireBus() acquires the I3C bus.

• HAL_I3C_ReleaseBus() releases the I3C bus.

Functions

hal_status_t HAL_I3C_AcquireBus ( hal_i3c_handle_t * hi3c , uint32_t timeout_ms )

Acquire the I3C bus thanks to the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_I3C_AcquireBus() must be called from thread mode only (not from handler mode i.e from ISR).

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_ReleaseBus ( hal_i3c_handle_t * hi3c )

Release the I3C bus thanks to the HAL OS abstraction layer (stm32_hal_os.c/.h osal).

Note

The HAL_I3C_ReleaseBus() must be called from thread mode only (not from handler mode i.e from ISR).

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_OK – Operation completed successfully

• HAL_ERROR – Operation completed with error

Set/get user data

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group11

A set of functions that manage a user data pointer stored in the I3C handle:

• HAL_I3C_SetUserData() set the user data into the handle

• HAL_I3C_GetUserData() get the user data from the handle

Functions

void HAL_I3C_SetUserData ( hal_i3c_handle_t * hi3c , const void * p_user_data )

Set the user data pointer into the handle.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_user_data – Pointer to the user data

const void * HAL_I3C_GetUserData ( const hal_i3c_handle_t * hi3c )

Get the user data pointer from the handle.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

void* – Pointer to the user data

Configuration functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group2

A set of functions that allow configuration of the I3Cx peripheral:

• Global configuration (controller):

  • HAL_I3C_CTRL_SetConfig()

  • HAL_I3C_CTRL_GetConfig()

• Global configuration (target):

  • HAL_I3C_TGT_SetConfig()

  • HAL_I3C_TGT_GetConfig()

• Payload ENTDAA configuration (target):

  • HAL_I3C_TGT_SetPayloadENTDAAConfig()

  • HAL_I3C_TGT_GetPayloadENTDAAConfig()

• FIFO configuration (target):

  • HAL_I3C_TGT_SetConfigFifo()

  • HAL_I3C_TGT_GetConfigFifo()

• FIFO configuration (controller):

  • HAL_I3C_CTRL_SetConfigFifo()

  • HAL_I3C_CTRL_GetConfigFifo()

• FIFO configuration unitary functions:

  • HAL_I3C_SetRxFifoThreshold()

  • HAL_I3C_GetRxFifoThreshold()

  • HAL_I3C_SetTxFifoThreshold()

  • HAL_I3C_GetTxFifoThreshold()

  • HAL_I3C_CTRL_EnableControlFifo()

  • HAL_I3C_CTRL_DisableControlFifo()

  • HAL_I3C_CTRL_IsEnabledControlFifo()

  • HAL_I3C_CTRL_EnableStatusFifo()

  • HAL_I3C_CTRL_DisableStatusFifo()

  • HAL_I3C_CTRL_IsEnabledStatusFifo()

• Own dynamic address (controller):

  • HAL_I3C_CTRL_SetConfigOwnDynamicAddress()

  • HAL_I3C_CTRL_GetConfigOwnDynamicAddress()

• Hot-Join allowed (controller):

  • HAL_I3C_CTRL_EnableHotJoinAllowed()

  • HAL_I3C_CTRL_DisableHotJoinAllowed()

  • HAL_I3C_CTRL_IsEnabledHotJoinAllowed()

• High keeper SDA configuration (controller):

  • HAL_I3C_CTRL_EnableHighKeeperSDA()

  • HAL_I3C_CTRL_DisableHighKeeperSDA()

  • HAL_I3C_CTRL_IsEnabledHighKeeperSDA()

• Stall time configuration (controller):

  • HAL_I3C_CTRL_SetConfigStallTime()

  • HAL_I3C_CTRL_GetConfigStallTime()

• Controller-Role request configuration (target):

  • HAL_I3C_TGT_EnableCtrlRoleRequest()

  • HAL_I3C_TGT_DisableCtrlRoleRequest()

  • HAL_I3C_TGT_IsEnabledCtrlRoleRequest()

• Group management support configuration (target):

  • HAL_I3C_TGT_EnableGroupAddrCapability()

  • HAL_I3C_TGT_DisableGroupAddrCapability()

  • HAL_I3C_TGT_IsEnabledGroupAddrCapability()

• Hot-Join configuration (target):

  • HAL_I3C_TGT_EnableHotJoinRequest()

  • HAL_I3C_TGT_DisableHotJoinRequest()

  • HAL_I3C_TGT_IsEnabledHotJoinRequest()

• In-Band Interrupt configuration (target):

  • HAL_I3C_TGT_SetConfigIBI()

  • HAL_I3C_TGT_GetConfigIBI()

  • HAL_I3C_TGT_EnableIBI()

  • HAL_I3C_TGT_DisableIBI()

  • HAL_I3C_TGT_IsEnabledIBI()

• Max data size configuration (target):

  • HAL_I3C_TGT_SetConfigMaxDataSize()

  • HAL_I3C_TGT_GetConfigMaxDataSize()

• GET MaX Data Speed (GETMXDS) configuration (target):

  • HAL_I3C_TGT_SetConfigGETMXDS()

  • HAL_I3C_TGT_GetConfigGETMXDS()

  • HAL_I3C_TGT_SetConfigGETMXDS_Format()

  • HAL_I3C_TGT_GetConfigGETMXDS_Format()

  • HAL_I3C_TGT_SetConfigCtrlHandOffActivity()

  • HAL_I3C_TGT_GetConfigCtrlHandOffActivity()

• Bus device configuration in DEVRX[] (controller):

  • HAL_I3C_CTRL_SetConfigBusDevices()

  • HAL_I3C_CTRL_GetConfigBusDevices()

• Reset pattern configuration (Controller):

  • HAL_I3C_CTRL_EnableResetPattern()

  • HAL_I3C_CTRL_DisableResetPattern()

  • HAL_I3C_CTRL_IsEnabledResetPattern()

Functions

hal_status_t HAL_I3C_CTRL_SetConfig ( hal_i3c_handle_t * hi3c , const hal_i3c_ctrl_config_t * p_config )

Configure the I3C as controller.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_CTRL_GetConfig ( const hal_i3c_handle_t * hi3c , hal_i3c_ctrl_config_t * p_config )

Retrieve the I3C controller configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_TGT_SetConfig ( hal_i3c_handle_t * hi3c , const hal_i3c_tgt_config_t * p_config )

Configure the I3C as target.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_TGT_GetConfig ( const hal_i3c_handle_t * hi3c , hal_i3c_tgt_config_t * p_config )

Retrieve the I3C target configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_TGT_SetPayloadENTDAAConfig ( const hal_i3c_handle_t * hi3c , const hal_i3c_tgt_config_payload_entdaa_t * p_config )

Set payload ENTDAA configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_TGT_GetPayloadENTDAAConfig ( const hal_i3c_handle_t * hi3c , hal_i3c_tgt_config_payload_entdaa_t * p_config )

Retrieve payload ENTDAA configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_CTRL_SetConfigFifo ( const hal_i3c_handle_t * hi3c , const hal_i3c_ctrl_fifo_config_t * p_config )

Set FIFO configuration when the I3C is acting as controller.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_SetConfigFifo ( const hal_i3c_handle_t * hi3c , const hal_i3c_tgt_fifo_config_t * p_config )

Set FIFO configuration when the I3C is acting as target.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_CTRL_GetConfigFifo ( const hal_i3c_handle_t * hi3c , hal_i3c_ctrl_fifo_config_t * p_config )

Retrieve FIFO configuration when the I3C is acting as controller.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

void HAL_I3C_TGT_GetConfigFifo ( const hal_i3c_handle_t * hi3c , hal_i3c_tgt_fifo_config_t * p_config )

Retrieve FIFO configuration when the I3C is acting as target.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_SetRxFifoThreshold ( const hal_i3c_handle_t * hi3c , const hal_i3c_rx_fifo_threshold_t threshold )

Set the Receive FIFO Threshold level configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• threshold – the Rx FIFO threshold

Return values :

HAL_OK – Operation completed successfully

hal_i3c_rx_fifo_threshold_t HAL_I3C_GetRxFifoThreshold ( const hal_i3c_handle_t * hi3c )

Get the receive FIFO threshold level configuration.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_RX_FIFO_THRESHOLD_1_8 – Rx Fifo Threshold is 1 byte.

• HAL_I3C_RX_FIFO_THRESHOLD_1_2 – Rx Fifo Threshold is 4 bytes.

hal_status_t HAL_I3C_SetTxFifoThreshold ( const hal_i3c_handle_t * hi3c , const hal_i3c_tx_fifo_threshold_t threshold )

Set the TX FIFO Threshold level configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• threshold – the Tx FIFO threshold

Return values :

HAL_OK – Operation completed successfully

hal_i3c_tx_fifo_threshold_t HAL_I3C_GetTxFifoThreshold ( const hal_i3c_handle_t * hi3c )

Get the TX FIFO Threshold level configuration.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_TX_FIFO_THRESHOLD_1_8 – Tx Fifo Threshold is 1 byte

• HAL_I3C_TX_FIFO_THRESHOLD_1_2 – Tx Fifo Threshold is 4 bytes

hal_status_t HAL_I3C_CTRL_EnableControlFifo ( hal_i3c_handle_t * hi3c )

Enable the Control FIFO.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DisableControlFifo ( hal_i3c_handle_t * hi3c )

Disable the Control FIFO.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_control_fifo_status_t HAL_I3C_CTRL_IsEnabledControlFifo ( const hal_i3c_handle_t * hi3c )

Check if the Control FIFO is enabled.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_CONTROL_FIFO_DISABLED – Control FIFO mode disabled

• HAL_I3C_CONTROL_FIFO_ENABLED – Control FIFO mode enabled

hal_status_t HAL_I3C_CTRL_EnableStatusFifo ( hal_i3c_handle_t * hi3c )

Enable the Status FIFO.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DisableStatusFifo ( hal_i3c_handle_t * hi3c )

Disable the Status FIFO.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_status_fifo_status_t HAL_I3C_CTRL_IsEnabledStatusFifo ( const hal_i3c_handle_t * hi3c )

Check if the Status FIFO is enabled.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_STATUS_FIFO_DISABLED – Status FIFO mode disabled

• HAL_I3C_STATUS_FIFO_ENABLED – Status FIFO mode enabled

hal_status_t HAL_I3C_CTRL_SetConfigOwnDynamicAddress ( hal_i3c_handle_t * hi3c , uint32_t dynamic_address )

Set dynamic address value.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• dynamic_address – Dynamic address

Return values :

HAL_OK – Operation completed successfully

uint32_t HAL_I3C_CTRL_GetConfigOwnDynamicAddress ( const hal_i3c_handle_t * hi3c )

Get dynamic address value.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

The – dynamic address

hal_status_t HAL_I3C_CTRL_EnableHotJoinAllowed ( hal_i3c_handle_t * hi3c )

Enable Hot-Join request acknowledgement allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DisableHotJoinAllowed ( hal_i3c_handle_t * hi3c )

Disable Hot-Join request acknowledgement allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_hot_join_status_t HAL_I3C_CTRL_IsEnabledHotJoinAllowed ( const hal_i3c_handle_t * hi3c )

Check if the Hot-Join request acknowledgement is enabled.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_HOT_JOIN_DISABLED – Hot-Join disable

• HAL_I3C_HOT_JOIN_ENABLED – Hot-Join enable

hal_status_t HAL_I3C_CTRL_EnableHighKeeperSDA ( const hal_i3c_handle_t * hi3c )

Enable the high keeper SDA.

Note

This configuration will be used in place of standard Open drain Pull Up device during handoff procedures

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DisableHighKeeperSDA ( const hal_i3c_handle_t * hi3c )

Disable the high keeper SDA.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_high_keeper_sda_status_t HAL_I3C_CTRL_IsEnabledHighKeeperSDA ( const hal_i3c_handle_t * hi3c )

Check if high keeper SDA is enabled.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_HIGH_KEEPER_SDA_DISABLED – The controller SDA high keeper disable

• HAL_I3C_HIGH_KEEPER_SDA_ENABLED – The controller SDA high keeper enable

hal_status_t HAL_I3C_CTRL_SetConfigStallTime ( const hal_i3c_handle_t * hi3c , uint32_t stall_time_cycle , uint32_t stall_features )

Set the SCL clock stalling configuration. All stall features not selected are disabled.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• stall_time_cycle – Controller clock stall time in number of kernel clock cycles. This parameter must be a number between Min_Data=0x00 and Max_Data=0xFF.

• stall_features – Features of the I3C controller to which the stall time will be applied. See Stall feature definition, this parameter is a combination of the following values: HAL_I3C_CTRL_STALL_ACK HAL_I3C_CTRL_STALL_CCC HAL_I3C_CTRL_STALL_TX HAL_I3C_CTRL_STALL_RX HAL_I3C_CTRL_STALL_I2C_ACK HAL_I3C_CTRL_STALL_I2C_TX HAL_I3C_CTRL_STALL_I2C_RX HAL_I3C_CTRL_STALL_ALL HAL_I3C_CTRL_STALL_NONE

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_GetConfigStallTime ( const hal_i3c_handle_t * hi3c , uint32_t * stall_time_cycle , uint32_t * stall_features )

Retrieve the SCL clock stalling configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• stall_time_cycle – Controller clock stall time in number of kernel clock cycles. This parameter must be a number between Min_Data=0x00 and Max_Data=0xFF.

• stall_features – Features of the I3C controller to which the stall time is applied. See Stall feature definition, this parameter is a combination of the following values: HAL_I3C_CTRL_STALL_ACK HAL_I3C_CTRL_STALL_CCC HAL_I3C_CTRL_STALL_TX HAL_I3C_CTRL_STALL_RX HAL_I3C_CTRL_STALL_I2C_ACK HAL_I3C_CTRL_STALL_I2C_TX HAL_I3C_CTRL_STALL_I2C_RX HAL_I3C_CTRL_STALL_ALL

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_EnableCtrlRoleRequest ( const hal_i3c_handle_t * hi3c )

Set Controller-Role Request allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_DisableCtrlRoleRequest ( const hal_i3c_handle_t * hi3c )

Set Controller-Role Request as not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_tgt_ctrl_role_status_t HAL_I3C_TGT_IsEnabledCtrlRoleRequest ( const hal_i3c_handle_t * hi3c )

Check if Controller-Role Request is allowed or not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_TGT_CTRL_ROLE_DISABLED – Controller-Role disable

• HAL_I3C_TGT_CTRL_ROLE_ENABLED – Controller-Role enable

hal_status_t HAL_I3C_TGT_EnableHandOffDelay ( const hal_i3c_handle_t * hi3c )

Set hand off delay allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_DisableHandOffDelay ( const hal_i3c_handle_t * hi3c )

Set hand off delay as not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_handoff_delay_status_t HAL_I3C_TGT_IsEnabledHandOffDelay ( const hal_i3c_handle_t * hi3c )

Check if hand off delay is allowed or not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_HANDOFF_DELAY_DISABLED – Handoff delay is disabled

• HAL_I3C_HANDOFF_DELAY_ENABLED – Handoff delay is enabled

hal_status_t HAL_I3C_TGT_EnableGroupAddrCapability ( const hal_i3c_handle_t * hi3c )

Set the group address capability as supported.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_DisableGroupAddrCapability ( const hal_i3c_handle_t * hi3c )

Set the group address capability as not supported.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_grp_addr_capability_status_t HAL_I3C_TGT_IsEnabledGroupAddrCapability ( const hal_i3c_handle_t * hi3c )

Check if the group address capability is supported or not-supported.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_GRP_ADDR_CAPABILITY_DISABLED – Group address capability disable

• HAL_I3C_GRP_ADDR_CAPABILITY_ENABLED – Group address capability enable

hal_status_t HAL_I3C_TGT_EnableHotJoinRequest ( const hal_i3c_handle_t * hi3c )

Set Hot-Join allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_DisableHotJoinRequest ( const hal_i3c_handle_t * hi3c )

Set Hot-Join as not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_hot_join_status_t HAL_I3C_TGT_IsEnabledHotJoinRequest ( const hal_i3c_handle_t * hi3c )

Check if Hot-Join is allowed or not-allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_HOT_JOIN_DISABLED – Hot-Join disable

• HAL_I3C_HOT_JOIN_ENABLED – Hot-Join enable

hal_status_t HAL_I3C_TGT_SetConfigIBI ( const hal_i3c_handle_t * hi3c , const hal_i3c_tgt_ibi_config_t * p_config )

Set IBI configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_TGT_GetConfigIBI ( const hal_i3c_handle_t * hi3c , hal_i3c_tgt_ibi_config_t * p_config )

Get IBI configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_TGT_EnableIBI ( const hal_i3c_handle_t * hi3c )

Enable IBI request.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_DisableIBI ( const hal_i3c_handle_t * hi3c )

Disable IBI request.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_tgt_ibi_status_t HAL_I3C_TGT_IsEnabledIBI ( const hal_i3c_handle_t * hi3c )

Check if IBI procedure is allowed or not allowed.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_TGT_IBI_DISABLED – IBI request disable

• HAL_I3C_TGT_IBI_ENABLED – IBI request enable

hal_status_t HAL_I3C_TGT_SetConfigMaxDataSize ( const hal_i3c_handle_t * hi3c , uint32_t max_read_data_size_byte , uint32_t max_write_data_size_byte )

Set the max data size configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• max_read_data_size_byte – Maximum read length the target advertises. This parameter must be a number between Min_Data=0x0 and Max_Data=0xFFFF.

• max_write_data_size_byte – Maximum read length the target advertises. This parameter must be a number between Min_Data=0x0 and Max_Data=0xFFFF.

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_GetConfigMaxDataSize ( const hal_i3c_handle_t * hi3c , uint32_t * p_max_read_data_size_byte , uint32_t * p_max_write_data_size_byte )

Retrieve max data size configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_max_read_data_size_byte – Pointer to maximum read length the target advertises.

• p_max_write_data_size_byte – Pointer to maximum write length the target advertises.

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_SetConfigGETMXDS ( const hal_i3c_handle_t * hi3c , const hal_i3c_tgt_getmxds_config_t * p_config )

Set the Max Data Speed configuration response for GETMXDS CCC.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_TGT_GetConfigGETMXDS ( const hal_i3c_handle_t * hi3c , hal_i3c_tgt_getmxds_config_t * p_config )

Retrieve the Max Data Speed configuration response for GETMXDS CCC.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_config – Pointer to the configuration structure

hal_status_t HAL_I3C_TGT_SetConfigGETMXDS_Format ( const hal_i3c_handle_t * hi3c , hal_i3c_getmxds_format_t format )

Set the format of the response for GETMXDS CCC.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• format – GETMXDS format

Return values :

HAL_OK – Operation completed successfully

hal_i3c_getmxds_format_t HAL_I3C_TGT_GetConfigGETMXDS_Format ( const hal_i3c_handle_t * hi3c )

Get the format of the response for GETMXDS CCC.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_GETMXDS_FORMAT_1 –

• HAL_I3C_GETMXDS_FORMAT_2_LSB –

• HAL_I3C_GETMXDS_FORMAT_2_MID –

• HAL_I3C_GETMXDS_FORMAT_2_MSB –

hal_status_t HAL_I3C_TGT_SetConfigCtrlHandOffActivity ( const hal_i3c_handle_t * hi3c , hal_i3c_handoff_activity_state_t state )

Set the activity state after Controller-Role handoff configuration.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• state – Handoff activity state

Return values :

HAL_OK – Operation completed successfully

hal_i3c_handoff_activity_state_t HAL_I3C_TGT_GetConfigCtrlHandOffActivity ( const hal_i3c_handle_t * hi3c )

Get the Activity State after Controller-Role handoff.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_HANDOFF_ACTIVITY_STATE_0 – Activity state 0 after handoff

• HAL_I3C_HANDOFF_ACTIVITY_STATE_1 – Activity state 1 after handoff

• HAL_I3C_HANDOFF_ACTIVITY_STATE_2 – Activity state 2 after handoff

• HAL_I3C_HANDOFF_ACTIVITY_STATE_3 – Activity state 3 after handoff

hal_status_t HAL_I3C_CTRL_SetConfigBusDevices ( const hal_i3c_handle_t * hi3c , const hal_i3c_ctrl_device_config_t * p_desc , uint32_t nb_device )

Set I3C bus devices configuration in DEVRX[].

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_desc – Pointer to the configuration structure

• nb_device – Number of devices to configure This parameter must be a value between Min_Data=1 and Max_Data=4

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

void HAL_I3C_CTRL_GetConfigBusDevices ( const hal_i3c_handle_t * hi3c , hal_i3c_ctrl_device_config_t * p_desc , uint32_t nb_device )

Retrieve I3C bus devices configuration from DEVRX[].

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_desc – Pointer to the configuration structure

• nb_device – Number of devices to retrieve the configuration This parameter must be a value between Min_Data=1 and Max_Data=4

hal_status_t HAL_I3C_CTRL_EnableResetPattern ( hal_i3c_handle_t * hi3c )

Enable the inserted reset pattern at the end of a frame.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DisableResetPattern ( hal_i3c_handle_t * hi3c )

Disable the inserted reset pattern at the end of a frame.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_reset_pattern_status_t HAL_I3C_CTRL_IsEnabledResetPattern ( const hal_i3c_handle_t * hi3c )

Check if the inserted reset pattern at the end of a frame is enabled or disabled.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_I3C_RESET_PATTERN_DISABLED – Standard STOP condition emitted at the end of a frame

• HAL_I3C_RESET_PATTERN_ENABLED – Reset pattern is inserted before the STOP condition of any emitted frame

hal_status_t HAL_I3C_CTRL_RegisterTransferCpltCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the controller transfer complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the controller transfer complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_RegisterDAACpltCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the controller dynamic address assignment complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the controller dynamic address assignment complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_RegisterTgtReqDynAddrCallback ( hal_i3c_handle_t * hi3c , hal_i3c_req_dyn_addr_cb_t p_callback )

Register the target request dynamic address callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the target request dynamic address callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_RegisterTxCpltCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the target transmission complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the target transmission complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_RegisterRxCpltCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the target Reception complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the target reception complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_RegisterHotJoinCallback ( hal_i3c_handle_t * hi3c , hal_i3c_tgt_hot_join_cb_t p_callback )

Register the target Hot-Join process complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the target Hot-Join process complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_RegisterNotifyCallback ( hal_i3c_handle_t * hi3c , hal_i3c_notify_cb_t p_callback )

Register the target/controller Notification event callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the target/controller Notification event callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_RegisterAbortCpltCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the abort complete callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the abort complete callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_RegisterErrorCallback ( hal_i3c_handle_t * hi3c , hal_i3c_cb_t p_callback )

Register the error callback.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_callback – Pointer to the error callback function

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_SetTxDMA ( hal_i3c_handle_t * hi3c , hal_dma_handle_t * hdma )

Link the transmit DMA handle to the I3C handle.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• hdma – Pointer to a hal_dma_handle_t structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_SetRxDMA ( hal_i3c_handle_t * hi3c , hal_dma_handle_t * hdma )

Link the receive DMA handle to the I3C handle.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• hdma – Pointer to a hal_dma_handle_t structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_SetTcDMA ( hal_i3c_handle_t * hi3c , hal_dma_handle_t * hdma )

Link the CR DMA handle to the I3C handle.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• hdma – Pointer to a hal_dma_handle_t structure

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

IRQ Handlers

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group4

A set of functions to handle the I3C interruptions:

• I3C Event IRQ Handler: HAL_I3C_EV_IRQHandler()

• I3C Error IRQ Handler: HAL_I3C_ERR_IRQHandler()

Depending on the process function used, different callbacks might be triggered:

Process API \ Callbacks	HAL_I3C_CTRL_DynAddrAssign_IT()
HAL_I3C_CTRL_DAACpltCallback()	x
HAL_I3C_CTRL_TgtReqDynAddrCallback()	x
HAL_I3C_ErrorCallback()	x

Process API \ Callbacks	HAL_I3C_CTRL_Transfer_IT()	HAL_I3C_CTRL_Transfer_DMA()
HAL_I3C_CTRL_TransferCpltCallback()	x	x
HAL_I3C_NotifyCallback() *	x	x
HAL_I3C_ErrorCallback()	x	x

Process API \ Callbacks	HAL_I3C_TGT_Transmit_IT()	HAL_I3C_TGT_Transmit_DMA()
HAL_I3C_TGT_TxCpltCallback()	x	x
HAL_I3C_NotifyCallback() *	x	x
HAL_I3C_ErrorCallback()	x	x

Process API \ Callbacks	HAL_I3C_TGT_Receive_IT()	HAL_I3C_TGT_Receive_DMA()
HAL_I3C_TGT_RxCpltCallback()	x	x
HAL_I3C_NotifyCallback() *	x	x
HAL_I3C_ErrorCallback()	x	x

Process API \ Callbacks	HAL_I3C_TGT_HotJoinReq_IT()
HAL_I3C_TGT_HotJoinCallback()	x
HAL_I3C_ErrorCallback()	x

Process API \ Callbacks	HAL_I3C_TGT_ControlRoleReq_IT()
HAL_I3C_NotifyCallback(HAL_I3C_TGT_NOTIFICATION_GETACCCR)	x
HAL_I3C_ErrorCallback()	x

Process API \ Callbacks	HAL_I3C_TGT_IBIReq_IT()
HAL_I3C_NotifyCallback(HAL_I3C_TGT_NOTIFICATION_IBIEND)	x
HAL_I3C_ErrorCallback()	x

Process API \ Callbacks	HAL_I3C_Abort_IT()
HAL_I3C_AbortCpltCallback()	x

Note

* HAL_I3C_NotifyCallback() is triggered if HAL_I3C_CTRL_ActivateNotification or HAL_I3C_TGT_ActivateNotification have been previously called in state HAL_I3C_STATE_IDLE

Functions

void HAL_I3C_ERR_IRQHandler ( hal_i3c_handle_t * hi3c )

Handle I3C error interrupt request.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_EV_IRQHandler ( hal_i3c_handle_t * hi3c )

Handle I3C event interrupt request.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

FIFO flush functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group5

A set of functions to flush FIFOs :

• HAL_I3C_FlushAllFifos() to flush the content of all used FIFOs (Control, Status, Tx and Rx FIFO).

• HAL_I3C_FlushTxFifo() to flush only the content of Tx FIFO.

• HAL_I3C_FlushRxFifo() to flush only the content of Rx FIFO.

• HAL_I3C_CTRL_FlushControlFifo() to flush only the content of Control FIFO.

• HAL_I3C_CTRL_FlushStatusFifo() to flush only the content of Status FIFO.

Functions

hal_status_t HAL_I3C_FlushAllFifos ( const hal_i3c_handle_t * hi3c )

Flush all I3C FIFOs content.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_FlushTxFifo ( const hal_i3c_handle_t * hi3c )

Flush I3C Tx FIFO content.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_FlushRxFifo ( const hal_i3c_handle_t * hi3c )

Flush I3C Rx FIFO content.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_FlushControlFifo ( const hal_i3c_handle_t * hi3c )

Flush I3C control FIFO content.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_FlushStatusFifo ( const hal_i3c_handle_t * hi3c )

Flush I3C status FIFO content.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

Controller transfer operation functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group6

A set of functions that manage controller I3C transfer operations:

• HAL_I3C_CTRL_ResetTransferCtx() to reset a transfer context.

• HAL_I3C_CTRL_InitTransferCtxTc() to provide a ctrl buffer. It will be filled by HAL_I3C_CTRL_BuildTransferCtxPrivate() or HAL_I3C_CTRL_BuildTransferCtxCCC().

• HAL_I3C_CTRL_InitTransferCtxTx() to provide the Tx buffer. It must be filled by application with concatenated Tx data.

• HAL_I3C_CTRL_InitTransferCtxRx() to provide the Rx buffer.

• HAL_I3C_CTRL_BuildTransferCtxPrivate() or HAL_I3C_CTRL_BuildTransferCtxCCC() to build transfer context

• HAL_I3C_CTRL_Transfer() to start transfer I3C or I2C private data or CCC command in multiple direction in polling mode.

• HAL_I3C_CTRL_Transfer_IT() to start transfer I3C or I2C private data or CCC command in multiple direction in interrupt mode.

• HAL_I3C_CTRL_Transfer_DMA() to start transfer I3C or I2C private data or CCC command in multiple direction in DMA mode.

• HAL_I3C_CTRL_DynAddrAssign() to send a broadcast ENTDAA CCC command in polling mode.

• HAL_I3C_CTRL_DynAddrAssign_IT() to send a broadcast ENTDAA CCC command in interrupt mode.

• HAL_I3C_CTRL_SetDynAddr() to set, associate the target dynamic address during the Dynamic Address Assignment process.

• HAL_I3C_CTRL_PoolForDeviceI3cReady() to check if I3C target device is ready.

• HAL_I3C_CTRL_PoolForDeviceI2cReady() to check if I2C target device is ready.

• HAL_I3C_CTRL_GeneratePatterns() to send HDR exit pattern or target reset pattern.

• HAL_I3C_CTRL_GenerateArbitration() to send arbitration (message header {S + 0x7E + W + STOP}) in polling mode.

• HAL_I3C_CTRL_RecoverSCLToIDLE() to force the stop of the SCL clock.

Functions

hal_status_t HAL_I3C_CTRL_ResetTransferCtx ( hal_i3c_transfer_ctx_t * p_ctx )

Reset a controller transfer context.

Parameters :

p_ctx – Pointer to the transfer context

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_InitTransferCtxTc ( hal_i3c_transfer_ctx_t * p_ctx , uint32_t * p_ctrl_buf , uint32_t size_word )

Initialize the transfer context with pointer to Transmit Control (TC) descriptor words buffer.

Parameters :

• p_ctx – Pointer to the transfer context

• p_ctrl_buf – Pointer to the Transmit Control (TC) buffer.

• size_word – Size in word of the Transmit Control (TC) buffer. size word = 2* number of description in case of direct CCC transfers size word = number of description for all other transfers Use helper macro HAL_I3C_GET_CTRL_BUFFER_SIZE_WORD

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_InitTransferCtxTx ( hal_i3c_transfer_ctx_t * p_ctx , const uint8_t * p_tx_data , uint32_t size_byte )

Initialize the transfer context with Tx data.

Parameters :

• p_ctx – Pointer to the transfer context

• p_tx_data – Pointer to the cumulated Tx buffer (HAL_I3C_DIRECTION_WRITE)

• size_byte – Size in byte of the cumulated Tx data

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_InitTransferCtxRx ( hal_i3c_transfer_ctx_t * p_ctx , uint8_t * p_rx_data , uint32_t size_byte )

Initialize the transfer context with Rx data.

Parameters :

• p_ctx – Pointer to the transfer context

• p_rx_data – Pointer to the cumulated Rx buffer (HAL_I3C_DIRECTION_READ)

• size_byte – Size in byte of the cumulated Rx data

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_BuildTransferCtxPrivate ( hal_i3c_transfer_ctx_t * p_ctx , const hal_i3c_private_desc_t * p_desc , uint32_t nb_desc , hal_i3c_transfer_mode_t mode )

Build a transfer context from private transfer descriptors.

Note

Preconditions on p_ctx (all must be satisfied before calling this function):

1. HAL_I3C_CTRL_ResetTransferCtx() was called (context cleared).

2. Control buffer provided via HAL_I3C_CTRL_InitTransferCtxTc():

   • p_ctx->p_tc_data != NULL

   • p_ctx->tc_size_word == nb_desc (exactly one control word per private descriptor)

3. If any descriptor has direction HAL_I3C_DIRECTION_WRITE:

   • HAL_I3C_CTRL_InitTransferCtxTx() was called

   • p_ctx->p_tx_data != NULL

   • p_ctx->tx_size_byte == sum of data_size_byte for all WRITE descriptors

4. If any descriptor has direction HAL_I3C_DIRECTION_READ:

   • HAL_I3C_CTRL_InitTransferCtxRx() was called

   • p_ctx->p_rx_data != NULL

   • p_ctx->rx_size_byte == sum of data_size_byte for all READ descriptors

5. If total write size or read size is zero, the corresponding pointer can be NULL.

6. mode must satisfy IS_I3C_PRIVATE_MODE(mode).

7. Function neither allocates nor modifies user data buffers; it only fills control words.

Parameters :

• p_ctx – Pointer to the transfer context

• p_desc – Pointer to the private transfer descriptor table.

• nb_desc – The number private transfer descriptor.

• mode – Transfer mode. It must be one of PRIVATE mode from hal_i3c_transfer_mode_t

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_BuildTransferCtxCCC ( hal_i3c_transfer_ctx_t * p_ctx , const hal_i3c_ccc_desc_t * p_desc , uint32_t nb_desc , hal_i3c_transfer_mode_t mode )

Build a transfer context from CCC transfer descriptor.

Note

Preconditions on p_ctx (all must be satisfied before calling this function):

1. HAL_I3C_CTRL_ResetTransferCtx() was called (context cleared).

2. Control buffer provided via HAL_I3C_CTRL_InitTransferCtxTc():

   • p_ctx->p_tc_data != NULL

   • For broadcast CCC: p_ctx->tc_size_word >= nb_desc (1 word per descriptor)

   • For direct CCC: p_ctx->tc_size_word >= (2 * nb_desc) (2 words per descriptor: CCC + target) After build, driver overwrites p_ctx->tc_size_word with the exact used size (nb_desc or 2*nb_desc).

3. Tx buffer requirements:

   • If any descriptor has direction HAL_I3C_DIRECTION_WRITE (broadcast or direct write): HAL_I3C_CTRL_InitTransferCtxTx() was called p_ctx->p_tx_data != NULL p_ctx->tx_size_byte == (sum of data_size_byte for all WRITE descriptors) + (sum of nb_define_bytes for all READ descriptors using a define byte)

4. Rx buffer requirements:

   • If any descriptor has direction HAL_I3C_DIRECTION_READ (direct read CCC only): HAL_I3C_CTRL_InitTransferCtxRx() was called p_ctx->p_rx_data != NULL p_ctx->rx_size_byte == sum over READ descriptors of (data_size_byte - nb_define_bytes)

5. If total computed tx_size_byte or rx_size_byte is zero, the corresponding pointer can be NULL.

6. mode must satisfy IS_I3C_CCC_MODE(mode).

7. Function only fills control words; it does not allocate or modify user data buffers.

Parameters :

• p_desc – Pointer to the CCC transfer descriptor table

• nb_desc – The number CCC transfer descriptor

• p_ctx – Pointer to the transfer context

• mode – Transfer mode. It must be one of CCC mode from hal_i3c_transfer_mode_t

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_Transfer ( hal_i3c_handle_t * hi3c , const hal_i3c_transfer_ctx_t * p_ctx , uint32_t timeout_ms )

Start transfer Direct CCC Command, I3C private or I2C transfer in polling mode.

Note

The function HAL_I3C_CTRL_BuildTransferCtxPrivate() must be called before initiating a private transfer or the function HAL_I3C_CTRL_BuildTransferCtxCCC() must be called before initiating a CCC transfer.

Note

The Tx FIFO threshold HAL_I3C_TX_FIFO_THRESHOLD_1_2 is not allowed when the transfer descriptor contains multiple CCC direct frames.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_ctx – Pointer to a hal_i3c_transfer_ctx_t structure. It can be reused to start again the same transfer. This transfer context is built by HAL_I3C_CTRL_BuildTransferCtxPrivate() or HAL_I3C_CTRL_BuildTransferCtxCCC().

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_Transfer_IT ( hal_i3c_handle_t * hi3c , const hal_i3c_transfer_ctx_t * p_ctx )

Start transfer Direct CCC Command, I3C private or I2C transfer in interrupt mode.

Note

The function HAL_I3C_CTRL_BuildTransferCtxPrivate() must be called before initiate a private transfer or the function HAL_I3C_CTRL_BuildTransferCtxCCC() must be called before initiate a CCC transfer.

Note

The Tx FIFO threshold HAL_I3C_TX_FIFO_THRESHOLD_1_2 is not allowed when the transfer descriptor contains multiple CCC direct frames.

Note

This function must be called to transfer read/write I3C or I2C private data or a direct read/write CCC.

Note

The tx_buf.size_byte must be equal to the sum of all tx_buf.size_byte exist in the descriptor.

Note

The rx_buf.size_byte must be equal to the sum of all rx_buf.size_byte exist in the descriptor.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_ctx – Pointer to a hal_i3c_transfer_ctx_t structure. It can be reused to start again the same transfer. This transfer context is filled by HAL_I3C_CTRL_BuildTransferCtxPrivate() or HAL_I3C_CTRL_BuildTransferCtxCCC().

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_Transfer_DMA ( hal_i3c_handle_t * hi3c , const hal_i3c_transfer_ctx_t * p_ctx )

Start transfer Direct CCC Command, I3C private or I2C transfer in DMA mode.

Note

The function HAL_I3C_CTRL_BuildTransferCtxPrivate() must be called before initiate a private transfer or the function HAL_I3C_CTRL_BuildTransferCtxCCC() must be called before initiate a CCC transfer.

Note

The Tx FIFO threshold HAL_I3C_TX_FIFO_THRESHOLD_1_2 is not allowed when the transfer descriptor contains multiple CCC direct frames.

Note

The tx_buf.size_byte must be equal to the sum of all tx_buf.size_byte exist in the descriptor.

Note

The rx_buf.size_byte must be equal to the sum of all rx_buf.size_byte exist in the descriptor.

Note

This function must be called to transfer read/write private data or a direct read/write CCC command.

Note

DMA widths:

• Tc: always words.

• Tx: threshold 1/8 -> bytes; threshold 1/2 -> words.

• Rx: threshold 1/8 -> bytes; threshold 1/2 -> words.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_ctx – Pointer to a hal_i3c_transfer_ctx_t structure. It can be reused to start again the same transfer. This transfer context is filled by HAL_I3C_CTRL_BuildTransferCtxPrivate() or HAL_I3C_CTRL_BuildTransferCtxCCC().

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_CTRL_DynAddrAssign ( hal_i3c_handle_t * hi3c , uint64_t * p_target_payload , hal_i3c_dyn_addr_opt_t option , hal_i3c_target_detection_status_t * p_target_detection_status , uint32_t timeout_ms )

Controller assigns dynamic addresses (broadcast ENTDAA CCC) in polling mode. ENTDAA is an iterative bus procedure: each target responds in turn with its 48-bit payload, after which the controller application must immediately associate a dynamic address via HAL_I3C_CTRL_SetDynAddr(). The hardware then automatically re-issues ENTDAA until “target not detected”. This function must be called in loop until p_target_detection_status indicates that no target is detected.

Note

Arbitration header is enabled.

Note

While (*p_target_detection_status == HAL_I3C_TGT_DETECTED):

• Retrieve the payload.

• Call HAL_I3C_CTRL_SetDynAddr() to assign a dynamic address.

• Call HAL_I3C_CTRL_DynAddrAssign() again to detect the next target. At the end of the DAA procedure (*p_target_detection_status == HAL_I3C_TGT_NOT_DETECTED):

• Call HAL_I3C_CTRL_SetConfigBusDevices() to register capabilities.

Note

Option HAL_I3C_DYN_ADDR_RSTDAA_THEN_ENTDAA inserts an initial RSTDAA CCC frame before ENTDAA.

Parameters :

• hi3c – I3C handle (controller mode required).

• p_target_payload – Pointer receiving the 48-bit target payload (PID[32] | BCR[8] | DCR[8]).

• option – HAL_I3C_DYN_ADDR_ONLY_ENTDAA or HAL_I3C_DYN_ADDR_RSTDAA_THEN_ENTDAA.

• p_target_detection_status – Pointer to the target detection status.

• timeout_ms – Timeout in milliseconds for internal flag waits.

Return values :

• HAL_OK – Operation completed successfully. The DAA process is completed if (*p_target_detection_status == HAL_I3C_TGT_NOT_DETECTED).

• HAL_ERROR – Operation completed with error.

• HAL_TIMEOUT – Operation exceeds user timeout.

• HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_I3C_CTRL_DynAddrAssign_IT ( hal_i3c_handle_t * hi3c , hal_i3c_dyn_addr_opt_t option )

Controller assigns dynamic addresses (broadcast ENTDAA CCC) in interrupt mode. ENTDAA is iterative: each target responds with a 48-bit payload (PID + BCR + DCR), after which the controller application must immediately associate a dynamic address via HAL_I3C_CTRL_SetDynAddr(). The hardware continues issuing ENTDAA until no further target responds.

Note

Option HAL_I3C_DYN_ADDR_RSTDAA_THEN_ENTDAA performs a preliminary RSTDAA CCC frame, then ENTDAA.

Note

Arbitration header is forced enabled during ENTDAA.

Note

After completion, call HAL_I3C_CTRL_SetConfigBusDevices() to register capabilities (addresses, IBI, etc.).

Parameters :

• hi3c – I3C handle (controller mode required).

• option – HAL_I3C_DYN_ADDR_ONLY_ENTDAA or HAL_I3C_DYN_ADDR_RSTDAA_THEN_ENTDAA.

Return values :

• HAL_OK – ENTDAA sequence accepted and configured; ISR will handle progress.

• HAL_BUSY – Concurrent process ongoing.

hal_status_t HAL_I3C_CTRL_SetDynAddr ( const hal_i3c_handle_t * hi3c , uint8_t target_address )

Controller Set dynamic address.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• target_address – Value of the dynamic address to be assigned

Return values :

• HAL_OK – Operation completed successfully

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_CTRL_PoolForDeviceI3cReady ( hal_i3c_handle_t * hi3c , uint8_t target_address , uint32_t timeout_ms )

Check whether an I3C target device is ready.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• target_address – Dynamic address of the target device

• timeout_ms – Polling timeout (in ms)

Return values :

• HAL_OK – Frame complete (FCF) detected: target is ready.

• HAL_TIMEOUT – User timeout elapsed: target not ready

• HAL_ERROR – Internal failure while waiting for hardware flags

hal_status_t HAL_I3C_CTRL_PoolForDeviceI2cReady ( hal_i3c_handle_t * hi3c , uint8_t target_address , uint32_t timeout_ms )

Check whether an I2C target device is ready.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• target_address – Address of the target device

• timeout_ms – Polling timeout (in ms)

Return values :

• HAL_OK – Frame complete (FCF) detected: target is ready.

• HAL_TIMEOUT – User timeout elapsed: target not ready

• HAL_ERROR – Internal failure while waiting for hardware flags

hal_status_t HAL_I3C_CTRL_GeneratePatterns ( hal_i3c_handle_t * hi3c , hal_i3c_pattern_opt_t pattern , uint32_t timeout_ms )

Controller generates patterns (target reset pattern or HDR exit pattern) with arbitration in polling mode.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• pattern – The generated pattern.

• timeout_ms – Timeout duration in ms.

Return values :

• HAL_OK – Operation completed successfully

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_CTRL_GenerateArbitration ( hal_i3c_handle_t * hi3c , uint32_t timeout_ms )

Controller generates arbitration (message header {S/Sr + 0x7E addr + W}) in polling mode.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• timeout_ms – Timeout duration

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

hal_status_t HAL_I3C_CTRL_RecoverSCLToIDLE ( const hal_i3c_handle_t * hi3c )

Recover the stuck SCL in case of CE1 error. It Forces the stop of the SCL clock.

Note

A minimum delay of 150 microseconds is required before emitting another message. This delay is approximately managed within this function.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

Target operational functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group7

A set of functions that manage target I3C operations:

• HAL_I3C_TGT_Transmit() to transmit private data in polling mode.

• HAL_I3C_TGT_Transmit_IT() to transmit private data in interrupt mode.

• HAL_I3C_TGT_Transmit_DMA() to transmit private data in DMA mode.

• HAL_I3C_TGT_Receive() to receive private data in polling mode.

• HAL_I3C_TGT_Receive_IT() to receive private data in interrupt mode.

• HAL_I3C_TGT_Receive_DMA() to receive private data in DMA mode.

• HAL_I3C_TGT_ControlRoleReq() to send a control-role request in polling mode.

• HAL_I3C_TGT_ControlRoleReq_IT() to send a control-role request in interrupt mode.

• HAL_I3C_TGT_HotJoinReq() to send a Hot-Join request in polling mode.

• HAL_I3C_TGT_HotJoinReq_IT() to send a Hot-Join request in interrupt mode.

• HAL_I3C_TGT_IBIReq() to send an IBI request in polling mode.

• HAL_I3C_TGT_IBIReq_IT() to send an IBI request in interrupt mode.

Functions

hal_status_t HAL_I3C_TGT_Transmit ( hal_i3c_handle_t * hi3c , const uint8_t * p_data , uint32_t size_byte , uint32_t timeout_ms )

Target transmit private data in polling mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

Target FIFO preload data is forced within this API for timing purpose.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_Transmit_IT ( hal_i3c_handle_t * hi3c , const uint8_t * p_data , uint32_t size_byte )

Target transmit private data in interrupt mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

This function returns HAL_ERROR if (DEFIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFTGTS) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

This function returns HAL_ERROR if (GRPIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFGRPA) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_Transmit_DMA ( hal_i3c_handle_t * hi3c , const uint8_t * p_data , uint32_t size_byte )

Target transmit private data in DMA mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

This function returns HAL_ERROR if (DEFIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFTGTS) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

This function returns HAL_ERROR if (GRPIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFGRPA) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

DMA widths:

• Tx: threshold 1/8 -> bytes; threshold 1/2 -> words.

• Rx: threshold 1/8 -> bytes; threshold 1/2 -> words.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_Receive ( hal_i3c_handle_t * hi3c , uint8_t * p_data , uint32_t size_byte , uint32_t timeout_ms )

Target receive private data in polling mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

This function returns HAL_ERROR if (DEFIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFTGTS) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

This function returns HAL_ERROR if (GRPIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFGRPA) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_Receive_IT ( hal_i3c_handle_t * hi3c , uint8_t * p_data , uint32_t size_byte )

Target receive private data in interrupt mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

This function returns HAL_ERROR if (DEFIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFTGTS) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

This function returns HAL_ERROR if (GRPIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFGRPA) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_Receive_DMA ( hal_i3c_handle_t * hi3c , uint8_t * p_data , uint32_t size_byte )

Target receive private data in DMA mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Note

This function returns HAL_ERROR if (DEFIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFTGTS) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

This function returns HAL_ERROR if (GRPIE | RXFNEIE) are set, HAL_I3C_TGT_ActivateNotification_IT(HAL_I3C_TGT_NOTIFICATION_DEFGRPA) enables these interrupts. This prevents Rx FIFO contention and mixing CCC payload bytes with private Tx data.

Note

DMA widths:

• Tx: threshold 1/8 -> bytes; threshold 1/2 -> words.

• Rx: threshold 1/8 -> bytes; threshold 1/2 -> words.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the data

• size_byte – Size of the data in bytes

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_ControlRoleReq ( hal_i3c_handle_t * hi3c , uint32_t timeout_ms )

Target sends Controller-Role request in polling mode.

Note

After receiving the controller’s response to the Controller-Role request, the application must configure the I3C as a controller using the HAL_I3C_CTRL_SetConfig() function.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_TGT_ControlRoleReq_IT ( hal_i3c_handle_t * hi3c )

Target sends Controller-Role request in interrupt mode.

Note

After receiving the controller’s response to the Controller-Role request, the application must configure the I3C as a controller using the HAL_I3C_CTRL_SetConfig() function.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_TGT_HotJoinReq ( hal_i3c_handle_t * hi3c , uint8_t * p_own_dynamic_address , uint32_t timeout_ms )

Target sends Hot-Join request in polling mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_own_dynamic_address – Pointer to the target own dynamic address assigned by the controller.

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_HotJoinReq_IT ( hal_i3c_handle_t * hi3c )

Target sends Hot-Join request in interrupt mode.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

hal_status_t HAL_I3C_TGT_IBIReq ( hal_i3c_handle_t * hi3c , const uint8_t * p_payload , uint32_t payload_size_byte , uint32_t timeout_ms )

Target sends IBI request in polling mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_payload – Pointer to the buffer contains the payload data

• payload_size_byte – Payload buffer size in bytes

• timeout_ms – Timeout duration in milliseconds

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_TIMEOUT – Operation exceeds user timeout

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_IBIReq_IT ( hal_i3c_handle_t * hi3c , const uint8_t * p_payload , uint32_t payload_size_byte )

Target sends IBI request in interrupt mode.

Note

The dynamic own address must be valid before calling this function. This function returns HAL_ERROR in these situations:

• Before the ENTDAA (Dynamic Address Assignment) procedure completes.

• Immediately after a RSTDAA (Reset Dynamic Address Assignment) broadcast.

• Before a successful Hot-Join sequence (target not yet assigned a dynamic address).

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_payload – Pointer to the buffer contains the payload data

• payload_size_byte – Payload buffer size in bytes

Return values :

• HAL_OK – Operation completed successfully

• HAL_BUSY – Concurrent process ongoing

• HAL_ERROR – Operation completed with error

• HAL_INVALID_PARAM – Invalid parameter

Weak callback functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group8

A set of Weak functions (or default callback functions if USE_HAL_I3C_REGISTER_CALLBACKS is set to 1) are used to asynchronously inform the application in non-blocking modes (interrupt and DMA):

• HAL_I3C_CTRL_TransferCpltCallback() : Controller multiple transfer completed callback.

• HAL_I3C_CTRL_DAACpltCallback() : Controller Dynamic Address Assignment complete callback.

• HAL_I3C_CTRL_TgtReqDynAddrCallback() : Target request Dynamic Address callback.

• HAL_I3C_TGT_TxCpltCallback() : Target transmission complete callback.

• HAL_I3C_TGT_RxCpltCallback() : Target reception complete callback.

• HAL_I3C_TGT_HotJoinCallback() : Target Hot-Join process complete callback.

• HAL_I3C_NotifyCallback() : Target/Controller notification event callback.

• HAL_I3C_ErrorCallback() : Target/Controller error callback.

• HAL_I3C_AbortCpltCallback() : Target/Controller abort callback.

Functions

void HAL_I3C_CTRL_TransferCpltCallback ( hal_i3c_handle_t * hi3c )

Controller Multiple transfer completed callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_CTRL_DAACpltCallback ( hal_i3c_handle_t * hi3c )

Controller dynamic address assignment complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_CTRL_TgtReqDynAddrCallback ( hal_i3c_handle_t * hi3c , uint64_t target_payload )

Target Request Dynamic Address callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• target_payload – Parameter indicates the target payload

void HAL_I3C_TGT_TxCpltCallback ( hal_i3c_handle_t * hi3c )

Target Transmission complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_TGT_RxCpltCallback ( hal_i3c_handle_t * hi3c )

Target Reception complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_TGT_HotJoinCallback ( hal_i3c_handle_t * hi3c , uint8_t dynamic_address )

Target Hot-Join process complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• dynamic_address – The returned dynamic address value after the Hot-Join process

void HAL_I3C_NotifyCallback ( hal_i3c_handle_t * hi3c , uint32_t notifications )

Target/Controller Notification event callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• notifications – Parameter indicates which notification is signaled It can be a combination value of Controller notification ID or Target notification ID.

void HAL_I3C_ErrorCallback ( hal_i3c_handle_t * hi3c )

Error callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

void HAL_I3C_AbortCpltCallback ( hal_i3c_handle_t * hi3c )

Abort complete callback.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Generic and common functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group9

A set of functions that abort transfers or retrieve the runtime status of the peripheral:

• HAL_I3C_Abort_IT() to abort the current transfer either in DMA or IT.

• HAL_I3C_GetState() to get the I3C handle state.

• HAL_I3C_GetMode() to get the I3C handle mode.

• HAL_I3C_GetLastErrorCodes() to get the last error code.

• HAL_I3C_GetClockFreq() to get the kernel clock frequency

• HAL_I3C_CTRL_GetENTDAA_PayloadInfo() to get BCR, DCR and PID information after ENTDAA.

• HAL_I3C_GetCCCInfo() to retrieve some specific associated CCC event data.

• HAL_I3C_GetDataCounter() to get the counter data.

Functions

hal_status_t HAL_I3C_Abort_IT ( hal_i3c_handle_t * hi3c )

Abort an I3C IT or DMA process communication with Interrupt.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

HAL_OK – Operation completed successfully

hal_i3c_state_t HAL_I3C_GetState ( const hal_i3c_handle_t * hi3c )

Return the I3C handle state.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

global_state –

• HAL_I3C_STATE_RESET Not yet Initialized

• HAL_I3C_STATE_INIT I3C is initialized but not yet configured

• HAL_I3C_STATE_IDLE I3C initialized and a global config applied

• HAL_I3C_STATE_TX Data Transmission process is ongoing

• HAL_I3C_STATE_RX Data Reception process is ongoing

• HAL_I3C_STATE_TX_RX Data Multiple Transfer process is ongoing

• HAL_I3C_STATE_DAA Dynamic address assignment process is ongoing

• HAL_I3C_STATE_TGT_REQ Target request process is ongoing

• HAL_I3C_STATE_ABORT Abort user request ongoing

hal_i3c_mode_t HAL_I3C_GetMode ( const hal_i3c_handle_t * hi3c )

Returns the I3C mode.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

Mode –

• HAL_I3C_MODE_NONE No I3C communication on going

• HAL_I3C_MODE_CTRL I3C communication is in controller mode

• HAL_I3C_MODE_TGT I3C communication is in target mode

uint32_t HAL_I3C_GetLastErrorCodes ( const hal_i3c_handle_t * hi3c )

Returns errors limited to the last process.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Returns :

uint32_t last error code. It can be HAL_I3C_ERROR_NONE or a combination of the following values: Controller protocol / parity / address phase errors:

• HAL_I3C_CTRL_ERROR_0 : Illegally formatted CCC

• HAL_I3C_CTRL_ERROR_1 : Transmitted data differs from expected

• HAL_I3C_CTRL_ERROR_2 : Broadcast address 0x7E not acknowledged

• HAL_I3C_CTRL_ERROR_3 : New controller did not drive the bus after controller-role hand-off Target protocol / parity / address phase errors:

• HAL_I3C_TGT_ERROR_0 : Invalid broadcast address 0x7E + W

• HAL_I3C_TGT_ERROR_1 : Parity error on a CCC code

• HAL_I3C_TGT_ERROR_2 : Parity error on a write data byte

• HAL_I3C_TGT_ERROR_3 : Parity error on the assigned address during dynamic address arbitration

• HAL_I3C_TGT_ERROR_4 : Missing 0x7E + R after Sr during dynamic address arbitration

• HAL_I3C_TGT_ERROR_5 : Illegally formatted CCC

• HAL_I3C_TGT_ERROR_6 : Transmitted data differs from expected Common data / flow errors:

• HAL_I3C_ERROR_DATA_HAND_OFF : Data error during Controller-Role hand-off; active controller keeps role

• HAL_I3C_ERROR_DATA_NACK : Data not acknowledged

• HAL_I3C_ERROR_ADDRESS_NACK : Address not acknowledged

• HAL_I3C_ERROR_COVR : Status FIFO over-run or Control FIFO under-run

• HAL_I3C_ERROR_DOVR : Rx FIFO over-run or Tx FIFO under-run

• HAL_I3C_TGT_ERROR_STALL : SCL held stable > timeout during SDR data read

• HAL_I3C_ERROR_DMA : DMA transfer error

• HAL_I3C_ERROR_DYNAMIC_ADDR : Dynamic address error

uint32_t HAL_I3C_GetDataCounter ( hal_i3c_handle_t * hi3c )

Get the data counter according to the current usecase (tgt/ctrl, transfer or not).

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Returns :

data counter:

• During the Dynamic Address Assignment process (ENTDAA CCC):

  • When the I3C acts as controller: number of targets detected.

  • When the I3C acts as target: number of transmitted bytes.

• During the transfer:

  • Whatever the I3C acts as controller or target: number of data bytes read from or transmitted on the I3C bus during the message.

hal_status_t HAL_I3C_GetCCCInfo ( const hal_i3c_handle_t * hi3c , uint32_t notifications , hal_i3c_ccc_info_t * p_ccc_info )

Target/Controller get the Common Command Code (CCC) information updated after notifications.

CCC Notification	Updated fields in p_ccc_info
HAL_I3C_TGT_NOTIFICATION_DAU	dynamic_addr, dynamic_addr_valid
HAL_I3C_TGT_NOTIFICATION_SETMWL	max_write_data_size_byte
HAL_I3C_TGT_NOTIFICATION_SETMRL	max_read_data_size_byte
HAL_I3C_TGT_NOTIFICATION_RSTACT	reset_action
HAL_I3C_TGT_NOTIFICATION_ENTAS_X	activity_state
HAL_I3C_TGT_NOTIFICATION_ENEC_DISEC	hot_join_allowed, in_band_allowed, ctrl_role_allowed
HAL_I3C_CTRL_NOTIFICATION_IBI	ibi_cr_tgt_addr, ibi_tgt_nb_payload, ibi_tgt_payload
HAL_I3C_CTRL_NOTIFICATION_CR	ibi_cr_tgt_addr

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• notifications – Notification. It can be a combination value of Controller notification ID or Target notification ID

• p_ccc_info – Pointer to an I3C_CCCInfoTypeDef structure that contains the CCC information updated after CCC event.

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

uint32_t HAL_I3C_GetClockFreq ( const hal_i3c_handle_t * hi3c )

Return the peripheral clock frequency for I3C.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t

Return values :

uint32_t – Frequency in Hz. 0 if the source clock of the I3C is not configured or not ready.

hal_status_t HAL_I3C_CTRL_GetENTDAA_PayloadInfo ( uint64_t entdaa_payload , hal_i3c_entdaa_payload_t * p_entdaa_payload )

Get BCR, DCR and PID information after ENTDAA.

Parameters :

• entdaa_payload – Payload received after ENTDAA

• p_entdaa_payload – Pointer to an I3C_ENTDAAPayloadTypeDef structure that contains the BCR, DCR and PID information.

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

Initialization and de-initialization functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group1

A set of functions that allow initialization and deinitialization of the I3Cx peripheral:

• HAL_I3C_Init(): initialize the selected device with the I3C instance.

• HAL_I3C_DeInit(): disable the peripheral.

Functions

hal_status_t HAL_I3C_Init ( hal_i3c_handle_t * hi3c , hal_i3c_t instance )

Initialize the I3C according to the associated handle.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• instance – HAL I3C instance

Return values :

• HAL_OK – HAL I3C instance has been correctly initialized.

• HAL_INVALID_PARAM – HAL I3C instance is NULL

• HAL_ERROR – HAL I3C semaphore creation is failed (USE_HAL_MUTEX is Set to 1)

void HAL_I3C_DeInit ( hal_i3c_handle_t * hi3c )

Deinitialize the HAL I3C driver for the given handle and disable the peripheral.

Parameters :

hi3c – Pointer to a hal_i3c_handle_t structure

Interrupt and callback functions

STM32C562xx STM32C5A3xx STM32C542xx

group I3C_Exported_Functions_Group3

A set of functions allowing the management of the notification feature of the I3Cx peripheral:

• HAL_I3C_CTRL_ActivateNotification() to activate the I3C notifications in controller mode.

• HAL_I3C_CTRL_DeactivateNotification() to deactivate the I3C notifications in controller mode.

• HAL_I3C_TGT_ActivateNotification() to activate the I3C notifications in target mode.

• HAL_I3C_TGT_DeactivateNotification() to deactivate the I3C notifications in target mode.

Functions

hal_status_t HAL_I3C_CTRL_ActivateNotification ( hal_i3c_handle_t * hi3c , uint32_t notifications )

Activate the I3C notifications in controller mode.

Warning

This weak function must not be modified. When the callback is needed, it is overridden in the user file.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• notifications – Notification. It can be a combination value of Controller notification ID

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_CTRL_DeactivateNotification ( hal_i3c_handle_t * hi3c , uint32_t notifications )

Deactivate the I3C notifications.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• notifications – Notification. It can be a combination value of Controller notification ID

Return values :

HAL_OK – Operation completed successfully

hal_status_t HAL_I3C_TGT_ActivateNotification ( hal_i3c_handle_t * hi3c , uint8_t * p_data , uint32_t size_byte , uint32_t notifications )

Activate the I3C notifications in target mode.

Note

If HAL_I3C_TGT_NOTIFICATION_DEFTGTS or HAL_I3C_TGT_NOTIFICATION_DEFGRPA is requested, p_data must be non-NULL and size_byte non-zero to capture the broadcast payload bytes.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• p_data – Pointer to the retrieve data during broadcast CCC DEFTGTS and DEFGRPA.

• size_byte – Size of retrieved data.

• notifications – Notification. It can be a combination value of Target notification ID

Return values :

• HAL_OK – Operation completed successfully

• HAL_INVALID_PARAM – Invalid parameter

hal_status_t HAL_I3C_TGT_DeactivateNotification ( hal_i3c_handle_t * hi3c , uint32_t notifications )

Deactivate the I3C notifications.

Parameters :

• hi3c – Pointer to a hal_i3c_handle_t

• notifications – Notification. It can be a combination value of Target notification ID

Return values :

HAL_OK – Operation completed successfully